feat(field): switch canonical route configurations - #4314

Summary

Add named multi-edge route configurations to the existing live FieldWellNetworkProcessUnit and canonical LoopedPipeNetwork.

• represent direct, brownfield reroute, and redundant/looped line-ups as immutable named options over existing edge IDs;
• apply a complete configuration transactionally with exact zero/one edge availability and full rollback;
• expose configuration.<selector>.selection through the existing ProcessAutomation action surface used by Field-to-facility production optimization: coupled wells, routing, equipment constraints and operating envelope #4188/[Campaign] Industrial-scale ProcessSystem and ProcessModel optimization #3154;
• retain the compatible one-edge route.* API and copy behavior;
• reject missing edges, duplicate line-ups, selector overlap, fractional selection, and undeclared current states;
• preserve each edge's typed equipment identity, geometry, thermal state, and Darcy-Weisbach/Beggs-Brill/two-fluid model.

This does not introduce another topology, hydraulic solver, optimizer, schedule, or cost model.

Engineering behavior

The synthetic live-well acceptance case uses one canonical graph with a primary two-edge path, a higher-resistance brownfield two-edge path, and a dual-path looped configuration. It verifies:

• process-automation discovery/read/write;
• lower deliverability and higher well backpressure on the restrictive brownfield path;
• positive flow through both branches in the redundant configuration;
• coupled network mass conservation;
• exact restoration of the primary operating point;
• unchanged hydraulic model selection;
• independent copied selector state; and
• fail-closed overlap, fractional-selection, and non-binary-state checks.

This is implementation plus synthetic integration/conservation/trend evidence. It is not field, laboratory, commercial-simulator, outage, brownfield, IPR/VLP, or hydraulic-correlation qualification.

Validation

Exact published commit: d0c8a432dfb858c9404b53dd91bb7d4d9ce930b2
Exact published tree: 7dd565dd58e96cce6821ea42186387a0aafd7c6b
Base: 7dc323b9bfc917f1fb000655857d316140605975

Passed locally:

• 111 adjacent JUnit tests; 0 failures/errors/skips:
  • FieldWellNetworkProcessUnitTest (5)
  • FieldToFacilityOptimizationAcceptanceTest (2)
  • FieldNetworkScaleAcceptanceTest (3)
  • ProcessAutomationTest (101)
• Spotless apply/check;
• Checkstyle;
• documentation search (788 Markdown, 1 HTML);
• generated engineering coverage --check (3,376 public types);
• PMD report generation; no new violation on the added configuration paths (repository baseline remains);
• git diff --check.

Local Javadocs were blocked by infrastructure because the runtime contains Java 17 JRE only and no javac/javadoc executable. Exact-head hosted Java 21 Javadocs and Java 8/21 model-specification jobs passed. The broader fast/slow matrix and remaining workflow groups are still running. The local pre-commit executable is absent; the exact-head hosted pre-commit workflow passed and mandatory direct gates were run. Keep this PR draft until all exact-head CI, review, and unresolved-thread checks complete.

Documentation impact

Updated the SURF integration guide and pipeline/network skill with the multi-edge line-up contract, automation address, validation boundary, and dependency-ordered continuation. Generated engineering coverage was refreshed.

Coordination

• [Campaign] State-of-the-art well, subsea gathering, injection and SURF network modelling/design #4228 owns the canonical field/SURF topology and this line-up contract.
• Field-to-facility production optimization: coupled wells, routing, equipment constraints and operating envelope #4188/[Campaign] Industrial-scale ProcessSystem and ProcessModel optimization #3154 consume the categorical process action; this PR does not duplicate their optimizer or accepted-point evidence work in feat(optimization): persist and revalidate field envelope evidence #4312.
• [Campaign] Professional reservoir-to-market dynamic process simulation #2911/Close the transient/dynamics parity gap: sustained severe slugging, liquid-rich stability, and a published controls benchmark #3298 retain transient/two-fluid qualification ownership.
• [Campaign] State-of-the-art NeqSim MCP process simulation and troubleshooting #3153 and [Campaign] Professional DEXPI and P&ID workflow #2899/[Campaign] Professional ISO 10628 PFD generation #1332 remain downstream agent/MCP and DEXPI identity consumers.

Next dependency

Exercise these configurations on the larger live production/injection field cases with qualified pump/compressor maps, shared host constraints, controlled reservoir-pressure updates, and lifecycle evidence. Independently qualify thermal/ST-F101/F109 route cases before design use.

Refs #4228, #4188, #3154, #2911, #3298, #3153, #2899, #1332.